Objetivo

Diseñar e implementar un módulo que, dado el contenido de la charla (campo contenido_charla de subtemas_curso) y considerando los antecedentes académicos personales de los postulantes (tabla profesores y sus profesor_documentos), calcule un porcentaje de cumplimiento y entregue un informe HTML completo con ranking y evidencias, almacenando un histórico de evaluaciones por subtema.

Decisión clave La profesión esperada se fija en subtemas_curso.especialista. No se modifica perfil_especialista_json (solo como antecedente si se consulta).

Alcance

Entrada: subtemas_curso (usa contenido_charla) y tablas de profesores + profesor_documentos.
Postulantes: <= 10; Documentos: ~2 por postulante.
Idioma: Español.
Sin eliminatorios: se usa umbral de cumplimiento (inicial: 60%), configurable.
Citas: solo nombre de archivo (no se requiere página).
Salida: Informe HTML + registro histórico en una tabla dedicada.

Arquitectura lógica (alto nivel)

Módulo Configuración: parámetros ajustables (umbral, pesos de score, catálogo de profesiones/sinónimos).
Módulo Clasificación de charla: resume el temario y sugiere profesión esperada; se escribe en subtemas_curso.especialista.
Módulo Matching: normaliza profesores.especialidad y cruza con especialista del subtema.
Módulo Evidencias: lectura de profesor_documentos, extracción de fragmentos relevantes, armado de citas (archivo + snippet).
Módulo Scoring: calcula match% (Cobertura 45, Experiencia 35, Actualidad 10, Comunicación 10 —configurable).
Generador de Informe: compone HTML con ranking, evidencias y brechas.
Histórico: persiste informe y resultados por subtema.

Backend: PHP (controladores + servicios).
AI: API Gemini para clasificación, resumen y evaluación dirigida (instrucciones estrictas de citar solo con nombre de archivo).
Almacenamiento: BD existente + nueva tabla subtema_evaluacion_hist.
Acceso Documentos: rutas locales accesibles (mismo host).
Seguridad: acceso autenticado a informes y documentos.

Modelo de datos (existente y nuevo)

Tablas existentes (resumen funcional)

Tabla	Uso en flujo	Campos relevantes
`subtemas_curso`	Fuente del temario; escritura de `especialista`.	`id`, `titulo`, `contenido_charla` (temario), `especialista` (profesión esperada), `perfil_especialista_json` (solo antecedente).
`profesores`	Catálogo de postulantes y su especialidad declarada.	`id`, `rut`, `nombre`, `apellidos`, `correo`, `telefono`, `ciudad`, `region`, `especialidad`, `cv_resumen`, `foto_perfil`.
`profesor_documentos`	Fuentes de evidencia para cada postulante.	`id_documento`, `profesor_id`, `nombre_documento`, `ruta_archivo`, `tipo`, `descripcion`, `fecha_doc`, `modo`.

Nueva tabla: histórico de evaluaciones

Se centraliza en una única tabla para mantener el rastro completo (informe HTML, parámetros, resultados y seleccionados).

Campo	Tipo sugerido	Descripción
`id`	PK, BIGINT	Identificador único de la evaluación.
`subtema_id`	FK → `subtemas_curso.id`	Subtema evaluado.
`fecha_evaluacion`	DATETIME	Fecha/hora de la ejecución.
`umbral_utilizado`	DECIMAL(5,2)	Ej.: 60.00.
`profesion_esperada`	VARCHAR(160)	Copia del valor vigente en `subtemas_curso.especialista`.
`parametros_json`	JSON	Peso de dimensiones, catálogo activo, etc.
`resumen_scores_json`	JSON	Lista: `[{id_profesor, match, dimensiones:{...}}]` (todos los evaluados).
`postulantes_seleccionados`	JSON	IDs de seleccionados (≥ umbral) en orden.
`brechas_json`	JSON	Checklist de “faltaría saber” por seleccionado.
`informe_html`	LONGTEXT	Informe completo renderizable.
`autor`	VARCHAR(120)	Usuario que ejecutó (opcional).
`hash_fuente`	VARCHAR(64)	Huella de `contenido_charla` (opcional) para trazabilidad.

Si en el futuro prefieres normalizar seleccionados a tabla hija, se crea subtema_evaluacion_seleccionado (1:N).

Parámetros de Configuración (ajustables)

Umbral: 60% (por defecto), rango sugerido 50–80%.
Pesos del Match Global: Cobertura 45, Experiencia 35, Actualidad 10, Comunicación 10.
Catálogo de profesiones: lista de valores estándar y sinónimos para normalizar profesores.especialidad.
Máximo de evidencias por candidato: 3–8 (para informe legible).
Longitud de snippet: 140–280 caracteres.
Modo de cita: solo nombre de archivo.
Idioma: ES (entrada/salida).
Riesgo por antigüedad: marcar evidencia si todo es anterior a N años (opcional, ej. 3).

Flujos funcionales

F1. Preparar profesión esperada del subtema

Seleccionar subtema en la UI.
Leer contenido_charla.
Resumir y clasificar (Gemini) para sugerir profesión/subárea.
Aprobar en UI y escribir en subtemas_curso.especialista.

F2. Filtrar postulantes compatibles

Tomar especialista del subtema.
Normalizar profesores.especialidad contra catálogo (sin tocar BD).
Filtrar candidatos cuyo mapeo sea compatible.
Listar candidatos preseleccionados.

F3. Extraer evidencias por candidato

Obtener documentos desde profesor_documentos por profesor_id.
Leer cada archivo (CV/títulos/certificados/otros).
Buscar señales de: Cobertura temática, Experiencia aplicada, Actualidad, Comunicación.
Guardar evidencias como: {archivo, snippet}.

F4. Calcular Match %

Calcular puntajes por dimensión (0–100).
Aplicar pesos configurados → match_global.
Generar “Faltaría saber” (brechas) para llegar a 100%.

F5. Generar informe HTML y guardar histórico

Ordenar por match_global.
Componer el informe HTML (cabecera de charla, resumen, detalle por candidato ≥ umbral, anexo opcional).
Persistir en subtema_evaluacion_hist con parámetros y resultados.
Exponer enlace/descarga del informe.

Endpoints y responsabilidades (sin código)

Endpoint	Entrada	Salida	Responsabilidad
`POST /config`	JSON: umbral, pesos, catálogo profesiones.	200 OK	Guardar parámetros (persistir en tabla propia o archivo seguro).
`POST /subtemas/:id/clasificar`	ID subtema.	Profesión esperada (texto) + sugerencias.	Clasificar con Gemini y escribir en `subtemas_curso.especialista` tras confirmación.
`POST /evaluar`	subtema_id	Informe HTML + resumen JSON	Matching, extracción de evidencias, scoring, generación de HTML y guardado en histórico.
`GET /historial/:subtema_id`	subtema_id	Lista de evaluaciones previas	Recuperar versiones previas (fecha, umbral, seleccionados, enlace a informe).
`GET /informe/:eval_id`	eval_id	HTML	Servir el HTML guardado en histórico.

Reglas de evaluación

Cobertura temática: proporción de subtemas del temario mencionados en documentos (evidencias citadas).
Experiencia aplicada: presencia de casos, proyectos, docencia o publicaciones alineadas con el temario.
Actualidad: evidencia reciente vs. antigüedad máxima configurable.
Comunicación: menciones a charlas/talleres/docencia.
Brechas (“faltaría saber”): subtemas o pruebas faltantes; redactado claro y accionable.

Privacidad y cumplimiento

Analizar solo contenido profesional; evitar atributos sensibles.
Restringir acceso a informes y documentos a usuarios autenticados/autorizados.
Registrar auditoría mínima: usuario ejecutor, fecha y subtema.
Incluir en informe solo citas necesarias (archivo + snippet) sin datos excesivos.

Plan de pruebas

Conjunto dorado: 3–5 subtemas + 6–10 postulantes con 2 docs c/u.
Validación manual: revisar que cada evidencia realmente existe en el archivo citado.
Pruebas de umbral: 50%, 60%, 70% para observar variación de seleccionados.
Stress: documentos escaneados/ruidosos; ausencia de evidencia reciente.
Regresión: si cambian pesos o catálogo, comparar resultados.

Cronograma detallado (hit-list ejecutable)

El cronograma asume 2–3 semanas con un equipo pequeño. Ajustar según tiempos internos.

Fase	Tareas concretas	Entregables	Responsable	Duración
0. Arranque	Confirmar acceso a BD y rutas de documentos. Definir catálogo de profesiones/sinónimos. Acordar pesos y umbral inicial (60%). Crear parámetros iniciales en Módulo Configuración.	Documento de catálogo; registro de parámetros.	PM + Dev	1–2 días
1. Clasificación	Implementar lectura de `contenido_charla`. Prompt de clasificación (Gemini) y normalización al catálogo. UI para aprobar y escribir en `subtemas_curso.especialista`.	Profesión esperada fijada por subtema.	Dev	2–3 días
2. Matching	Normalizador de `profesores.especialidad` contra catálogo. Filtro de postulantes compatibles.	Listado de preseleccionados.	Dev	1–2 días
3. Evidencias	Recorrer `profesor_documentos`; lectura de archivos. Extracción de snippets (archivo + fragmento). Ensayos de calidad: longitud/claridad.	Repositorio de evidencias por candidato.	Dev	2–3 días
4. Scoring	Calcular dimensiones y `match_global` con pesos. Generar “faltaría saber”. Aplicar umbral para seleccionados.	Scores por candidato + brechas.	Dev	1–2 días
5. Informe & Histórico	Componer HTML completo (cabecera, resumen, detalle, anexo). Crear `subtema_evaluacion_hist` y persistir parámetros/resultados/HTML. Exponer endpoints de consulta.	Informe HTML almacenado y consultable.	Dev	2 días
6. Pruebas & Cierre	Ejecutar plan de pruebas (dorados, umbrales, stress). Ajustes finales de pesos/umbral/catálogo si corresponde. Capacitación de usuarios.	Go-live controlado.	PM + Dev	2–3 días

Criterios de aceptación

Para un subtema dado, se fija especialista y se obtiene una lista de candidatos con match %.
El informe HTML muestra solo quienes ≥ umbral (configurable) y expone evidencias con nombre de archivo.
Se guarda un registro en subtema_evaluacion_hist con parámetros, resultados y el HTML exacto.
Un usuario autorizado puede consultar histórico por subtema y abrir el informe.

Riesgos y mitigaciones

Especialidad libre: inconsistencias → normalización por catálogo y sinónimos.
Evidencia escasa: pocos documentos → enfatizar “faltaría saber”.
Contenido antiguo: sin recencia → marcar como brecha.
OCR: si hubiera escaneos → permitir carga manual de texto alternativo.

Contexto

En subtemas_curso.contenido_charla está el contenido a enseñar. Los documentos de los postulantes son sus antecedentes académicos personales. El sistema debe citar únicamente el nombre de archivo como evidencia.

Umbral inicial 60% de cumplimiento; ajustable en Configuración. Pesos iniciales: Cobertura 45, Experiencia 35, Actualidad 10, Comunicación 10 (también ajustables).

Prompts ejemplo (solo texto, sin código)

Estos textos se usan como instrucciones para la IA (Gemini). Pueden ajustarse en el área de Configuración.

P1 — Clasificación de la charla (profesión esperada)

Objetivo: Dado el temario extenso en contenido_charla, proponer 1–3 profesiones (y subáreas) que mejor se ajusten. El resultado final se escribe en subtemas_curso.especialista en formato “Profesión / Subárea”.

Instrucciones a la IA:

Eres un analista académico. Lee el temario y sugiere las profesiones/subáreas más pertinentes para impartir la charla.
Devuelve entre 1 y 3 opciones, cada una con: nombre (“Profesión / Subárea”), breve justificación y un score de adecuación (0–1).
Evita profesiones que no tengan relación directa con el temario.
Tu salida debe ser breve y clara.

Entradas: título del subtema + contenido_charla.

Salida deseada (texto natural): “Profesión esperada: Abogado / Laboral (0.84). Alternativas: Abogado / Corporativo (0.58) — Justificación: …”

P2 — Extracción de evidencias por candidato

Objetivo: Leer 1–2 documentos por postulante y extraer fragmentos que demuestren cobertura temática, experiencia aplicada, actualidad y comunicación. Citar solo nombre de archivo.

Instrucciones a la IA:

Analiza los documentos adjuntos del postulante. Extrae entre 3 y 8 fragmentos como evidencias.
Clasifica cada evidencia en: Cobertura, Experiencia, Actualidad o Comunicación.
Para cada evidencia, indica: archivo (nombre) y snippet (140–280 caracteres, sin datos sensibles innecesarios).
No inventes información; si no hay evidencia explícita, señala “no encontrado”.

Entradas: nombre del postulante + nombres de archivos + texto extraído.

Salida deseada: lista de evidencias con tipo, archivo y snippet.

P3 — Scoring y “faltaría saber”

Objetivo: Calcular puntajes 0–100 por dimensión y un match_global ponderado. Indicar brechas específicas para llegar a 100%.

Instrucciones a la IA:

Asigna puntajes por dimensión con base en las evidencias: Cobertura, Experiencia, Actualidad, Comunicación.
Calcula match_global = suma ponderada de las cuatro dimensiones con los pesos configurados.
Enumera “faltaría saber”: subtemas del temario sin evidencia, certificados no demostrados, desactualización, etc.
No incluyas datos sensibles. Redacción breve y accionable.

Entradas: profesión esperada, lista de subtemas clave, evidencias por candidato, pesos.

Salida deseada: match_global + detalle por dimensión + lista de brechas.

P4 — Generación del informe (composición)

Objetivo: Componer texto ordenado para el informe HTML (cabecera, resumen, detalle por candidato ≥ umbral, anexo opcional).

Instrucciones a la IA:

Ordena a los candidatos por match_global.
Incluye solo quienes estén por encima del umbral.
Para cada uno, produce: identificación, perfil, match global y por dimensión, evidencias (archivo + snippet), “faltaría saber”, lista de documentos analizados.
Usa frases claras y concisas.

Entradas: profesión esperada, umbral, lista de candidatos con resultados.

Salida deseada: bloques de texto listos para insertar en HTML.

Anexo — Plantilla del informe para un subtema

Rellena los campos entre llaves { } con datos del sistema.

1) Cabecera

Subtema	{ subtema.titulo }
Profesión esperada	{ subtema.especialista }
Fecha evaluación	{ fecha_evaluacion }
Umbral	{ umbral }%

Resumen del contenido: { resumen_contenido_charla }

2) Resumen ejecutivo

Postulantes evaluados: { total_postulantes }
Seleccionados (≥ { umbral }%): { total_seleccionados }

3) Ranking de seleccionados

{ filas_ranking }

#	Postulante	Especialidad (texto original)	Match %

4) Detalle por postulante (≥ umbral)

4.x { postulante.nombre_completo } — { match_global }%

Identificación: RUT { postulante.rut } · Correo { postulante.correo } · Tel { postulante.telefono } · { postulante.ciudad }/{ postulante.region }

Perfil: Especialidad declarada: “{ postulante.especialidad }”

Dimensión	Puntaje
Cobertura temática	{ d.cobertura } / 100
Experiencia aplicada	{ d.experiencia } / 100
Actualidad	{ d.actualidad } / 100
Comunicación	{ d.comunicacion } / 100

Evidencias citadas (archivo + snippet)

{ lista_evidencias }

Faltaría saber (brechas)

{ lista_brechas }

Documentos analizados

{ lista_documentos }

5) Anexo (opcional) — Postulantes bajo el umbral

{ filas_bajo_umbral }

Postulante	Match %	Notas

6) Metadatos de la evaluación

Pesos usados	Cobertura { pesos.cobertura } · Experiencia { pesos.experiencia } · Actualidad { pesos.actualidad } · Comunicación { pesos.comunicacion }
Autor	{ autor }
Hash fuente (opcional)	{ hash_fuente }

Notas de implementación (recordatorio)

Usar solo nombre de archivo en citas de evidencias.
No modificar perfil_especialista_json.
Guardar el informe renderizado en subtema_evaluacion_hist.informe_html junto con parámetros y resultados.
Parámetros (umbral, pesos, catálogo) expuestos en Configuración.